Agent

The agent contract — what application code depends on (best practice #7). ToolLoopAgent is the default implementation, but other implementations exist (e.g. a DurableAgent that journals to disk for offline-resilient mode, a SubagentTestAgent that records calls for unit tests).

Application code should depend on this interface, not on ToolLoopAgent.

Approval flow

Per v6 RPC semantics, when a tool needs approval the loop ends:

GenerateResult.pendingApprovals is populated with PendingApprovals
GenerateResult.messages contains the assistant message with ContentPart.ToolApprovalRequest parts appended

The host resumes by calling generate again with:

agent.generate(
  messages = result.messages + toolApprovalResponseMessage(toolCallId, approved = true),
  options = ...
)

No submitApproval method exists — state lives entirely in the message list so it can be serialized, persisted across process restarts, and replayed.

Type Parameters

TContext

typed application context (RAG state, user IDs, request metadata) propagated through the loop. Set via the agent constructor's callOptionsSchema and passed at call time via generate / stream.

TOutput

agent's terminal output type. For free-form chat agents it's String; for structured-output agents (with Output set) it's the typed shape.

Inheritors

ToolLoopAgent

Properties

open val id: String

Stable identifier for the agent, useful for telemetry, log routing, and the Agent.version / id / tools accessors v6 exposes (per historical parity gap #33). Implementations default to "agent"; override in the constructor or via class member to set a more specific tag ("chat-agent", "lineup-subagent", etc.).

tools

abstract val tools: ToolSet<TContext>

The tool surface this agent carries. Exposed at the interface so consumers can inspect / dispatch without casting to ToolLoopAgent.

version

open val version: String?

Optional version string — "1.0.0", a git sha, anything stable across an app build. Null = unversioned. Lets telemetry pin issues to a specific agent revision.

Functions

generate

abstract suspend fun generate(prompt: String? = null, messages: List<ModelMessage> = emptyList(), options: TContext? = null, abortSignal: AbortSignal = AbortSignalNever, hooks: AgentCallHooks? = null): GenerateResult<TOutput>

One-shot generation. Either prompt or messages (or both) must be supplied. When both are present, prompt is appended as a trailing user message.

session

fun <TContext, TOutput> Agent<TContext, TOutput>.session(scope: CoroutineScope, initialMessages: List<ModelMessage> = emptyList()): AgentSession<TContext, TOutput>

stream

abstract fun stream(prompt: String? = null, messages: List<ModelMessage> = emptyList(), options: TContext? = null, abortSignal: AbortSignal = AbortSignalNever, hooks: AgentCallHooks? = null): Flow<StreamEvent>

Streaming generation. Cold flow — starts when collected.